Add Qiskit route/validity/cost-phase construction with Aer table reproduction - #1

Implements a Qiskit circuit version of the paper’s construction while preserving the existing PennyLane implementation. Adds an Aer statevector example that reproduces the tour table (tour, (\phi), validity) and renders the full table as a plot.

• Qiskit construction module (src/qiskit_route_construction.py)

  • Introduces explicit register layout for route, validity ancillas, good, and phase ancilla.
  • Implements reversible validity oracle as separate compute/uncompute passes.
  • Implements validity-controlled cost-phase oracle (start edge, internal transitions, return edge).
  • Adds helpers for route decoding, classical validity/cost reference, and phase-table generation.

• Paper-style Aer example (qiskit_route_construction_example.py)

  • Builds normalized TSP instance (n=5, seed=42 default), runs statevector simulation, and emits full table.
  • Outputs:
    • qiskit_tsp_table.csv
    • qiskit_tsp_table.png (all entries plotted as a table figure).

• Test coverage (tests/test_qiskit_route_construction.py)

  • Verifies oracle marks only permutation-valid routes.
  • Verifies valid-route relative phase matches classical route cost differences.
  • Verifies ancilla cleanup after uncomputation (no residual probability outside ancilla-zero subspace).

• Project integration

  • Adds Qiskit/Aer + plotting/test dependencies in requirements.txt.
  • Extends README with concise usage for the new Qiskit flow.

from src.qiskit_route_construction import build_qiskit_tsp_construction_circuit
from qiskit_aer import Aer

circuit, layout = build_qiskit_tsp_construction_circuit(cost_matrix, start_node=4)
state = Aer.get_backend("statevector_simulator").run(circuit).result().get_statevector(circuit)